.\"  -*- nroff -*-
.\"
.\" csvprintf - Simple CSV file parser for the UNIX command line
.\" 
.\" Copyright 2010 Archie L. Cobbs <archie@dellroad.org>
.\" 
.\" Licensed under the Apache License, Version 2.0 (the "License"); you may
.\" not use this file except in compliance with the License. You may obtain
.\" a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
.\" 
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.\" WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.\" License for the specific language governing permissions and limitations
.\" under the License.
.\"
.\" $Id$
.\"
.Dd November 30, 2010
.Dt CSVPRINTF 1
.Os
.Sh NAME
.Nm csvprintf
.Nd Simple CSV file parser for the UNIX command line
.Sh SYNOPSIS
.Nm csvprintf
.Bk -words
.Op Fl i
.Op Fl q Ar char
.Op Fl s Ar char
.Op Fl f Ar file
.Ar format
.Ek
.Pp
.Nm csvprintf
.Bk -words
.Op Fl i
.Op Fl q Ar char
.Op Fl s Ar char
.Op Fl f Ar file
.Op Fl e Ar enc
.Fl x
.Ek
.Pp
.Nm xml2csv
.Bk -words
.Op Ar file.xml
.Ek
.Sh DESCRIPTION
.Nm
is a simple UNIX command line utility for parsing CSV files.
.Pp
.Nm
works like the
.Xr printf 1
command line utility.
You supply a
.Xr printf 1
format string on the command line and each record of the CSV file is formatted accordingly.
Each format specifier in the format string is required to start with a column accessor to specify which CSV column to use.
.Pp
The column accessor is a sequence of decimal digits followed by the ``$'' character (the same accessor format supported by
.Xr printf 1 ) .
So for example,
``%3$d''
would format the third CSV column as a decimal value.
In addition, the ``%0$d'' specifier will print the number of columns in the record.
.Pp
Under the hood,
.Nm
invokes the
.Xr printf 1
executable on each CSV row it parses.
.Pp
.Nm
can also convert CSV files into XML documents.
The
.Nm xml2csv
command converts XML documents so generated back into CSV files.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl e
Specify input character encoding.
By default, ISO-8859-1 is assumed.
This option only affects XML mode.
.It Fl f
Read CSV input from the specified file.
By default (or if ``-'' is specified),
.Nm
reads from standard input.
.It Fl i
Ignore the very first CSV record in the input (typically contains column names).
.It Fl q
Specify an alternate CSV column quote character.
The usual backslash escape sequences are accepted.
The default quote character is double quote.
.It Fl s
Specify an alternate CSV column separator character.
The usual backslash escape sequences are accepted.
The default separator character is comma.
.It Fl h
Output usage message and exit.
.It Fl v
Output version information and exit.
.It Fl x
Convert the CSV input into an XML document.
If the input character encoding is other than ISO-8859-1, specify using the
.Fl e
flag.
.El
.Sh CSV FORMAT
.Nm
parses according to the format described by ``The Comma Separated Value (CSV) File Format'' (see below).
In particular, quote characters must be escaped with an extra quote and whitespace surrounding column values is ignored.
.Sh EXIT STATUS
.Nm
will exit with a status 1 if invalid CSV input is detected.
Otherwise, if an invocation of
.Xr printf 1
fails, processing stops and that exit value is returned.
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa @pkgdatadir@/csv.xsl
XSL transform that converts XML back into CSV format.
.El
.Sh SEE ALSO
.Xr printf 1 ,
.Xr printf 3 .
.Rs
.%T "csvprintf: Simple CSV file parser for the UNIX command line"
.%O http://csvprintf.googlecode.com/
.Re
.Rs
.%T "The Comma Separated Value (CSV) File Format"
.%O http://www.creativyst.com/Doc/Articles/CSV/CSV01.htm
.Re
.Sh AUTHOR
.An Archie L. Cobbs Aq archie@dellroad.org
